[slopfix] docs(self-hosting): promote postgres from experimental to recommended OSS multi-node backend - #5341

Stack for rivet-dev/rivet

• #5552 [slopfix] fix(universaldb): match fdb conflict semantics in …
• #5551 [slopfix] fix(universaldb,util,pegboard-envoy): index dedup …
• #5398 feat(kitchen-sink): add churnDb actor and seed driver for co …
• #5397 chore: Clean up
• #5382 [slopfix] docs(self-hosting): correct postgres config format …
• #5356 [slopfix] fix(pegboard): decrement kv_storage_used metric on …
• #5354 [slopfix] refactor(universaldb,ups): single/multi-node udb o …
• #5353 [slopfix] perf(universaldb): fold postgres drain_batch into …
• #5342 [SLOP(claude-opus-4-8-high)] perf(universaldb): batch leader …
• #5341 [slopfix] docs(self-hosting): promote postgres from experime … 👈
• #5340 [slopfix] fix(self-host): repair dev compose generation, kit …
• #5337 [SLOP(claude-opus-4-8-high)] feat(universaldb): graceful pos …
• #5336 [slopfix] test(universaldb): postgres leader failover + abor …
• #5335 [SLOP(claude-opus-4-8-high)] feat(ups): table-backed postgre …
• #5329 [SLOP(claude-opus-4-8-high)] feat(universaldb): postgres lea …
• #5327 [SLOP(claude-opus-4-8)] feat(pegboard-envoy): rate-limit env …
• #5326 [SLOP(claude-opus-4-8)] feat(util): add rate limiter primiti …
• #5322 [SLOP(claude-opus-4-8)] feat(rivetkit-core): add serde durat …
• #5321 Add observation for serde_bare
• #5320 Add observation and ser/de metrics for serde calls
• #5314 [SLOP(claude-opus-4-8-medium)] chore: add profiling cargo pr …
• #5306 [SLOP(claude-opus-4-8)] fix(kitchen-sink): serve built front …
• main

Get stack: forklift get 5341
Push local edits: forklift submit
Merge when ready: forklift merge 5341

_{change zsmysquk}

Review

Docs-only PR promoting PostgreSQL from experimental to recommended for multi-node self-hosting. Overall the new postgres.mdx sections (connection limits, resources, HA/backups, troubleshooting) are clear and well-organized. A few issues worth addressing before merge.

1. New NATS guidance contradicts the file most closely related to it (and one this PR itself edits)

vpc-air-gapped.mdx now says:

The built-in PostgreSQL pub/sub is sufficient for most deployments; very high-throughput deployments can add NATS as a dedicated pub/sub layer.

I checked this against the engine code and it's accurate: engine/packages/config/src/config/mod.rs auto-defaults pubsub to PostgresNotify (LISTEN/NOTIFY-backed, in engine/packages/universalpubsub/src/driver/postgres/) whenever database is Postgres and no pubsub is explicitly set. NATS is not required.

However, postgres.mdx, edited extensively elsewhere in this same PR, still says the opposite in sections this PR left untouched:

• "Multi-node: Use PostgreSQL as the database and NATS for pub/sub." (Choosing a Backend)
• "Multi-node PostgreSQL deployments require NATS as the pub/sub backend so engine nodes can coordinate." (Pub/Sub (NATS) section)

And production-checklist.mdx (also untouched by this PR) has a ## NATS section stating "Use NATS for pub/sub in multi-node deployments... NATS is the pub/sub backend that coordinates realtime messaging between engine nodes," with no mention that it's optional.

Since this PR is already reworking the multi-node PostgreSQL story and touches postgres.mdx directly, it would be worth fixing the "NATS required" language there and in production-checklist.mdx in the same change, rather than leaving contradictory claims live across the docs (one page says NATS is required for multi-node, the new page says it's only needed at high throughput).

2. /docs/self-hosting/multi-region is a stub

The new "Multi-Region" bullet in the Overview and the new ### Multi-Region section both link to /docs/self-hosting/multi-region with "see the full topology," but that page currently only contains <Info>Documentation coming soon</Info>. Minor, but the link promises content that doesn't exist yet. Consider softening the phrasing or filing a follow-up to fill in that page.

3. max_connections x 150 figure isn't derived from a code constant

I checked the actual pool sizing: each engine node opens two separate deadpool-postgres pools hardcoded to max_size: 64 (UDB in universaldb/src/driver/postgres/database.rs and the Postgres-notify pubsub driver in universalpubsub/src/driver/postgres/mod.rs), plus two dedicated non-pooled LISTEN connections, roughly 130 per node today, and neither pool size is currently configurable. The qualitative claim ("well over a hundred per node") holds, and 150 is a reasonable safety margin, but it reads as if it were a derived constant. Worth a footnote that it's a rule-of-thumb headroom figure rather than a fixed value, since a future change to the hardcoded 64 would silently invalidate the doc's math.

Minor nits

• Double blank line before ## Troubleshooting in postgres.mdx (trailing artifact from the diff).

Nothing here blocks the core content improvements. Item 1 is the one I'd actually want resolved before merge, since it currently leaves the self-hosting docs giving readers opposite answers to "do I need NATS?" depending on which page they land on.